Pull Requestに関する意見
原則
レビューのしやすいPull Requestを作成することはレビュイーの責任
レビュイーの方がレビュワーよりもPull Requestにまつわるコンテキストを多く持っているため、レビュイーがレビュワーに向けて過不足なく説明をすべき。
わからないPull Requestはわからないと言って良い。
Pull Requestはレビュイーの持ち物である。
自分でレビューを促す必要がある。チームのルールを破らなければ、自分で満足したらマージボタンを押して良い。
プラクティス
Pull RequestにはなぜこのPull Requestをマージするべきなのかの理由が書かれているべき。
「なぜやるのか?」から入ることで文脈の共有が行いやすい。もっと良いHowを提案できる可能性がある。(なおPRでそれをやっているのは基本的には遅いことが多い。)
Pull Requestには要件そのものに1クリック以内でたどれる情報がなくてはいけない。
2クリック以上させてはいけない。すぐにPull Requestのレビューに必要な情報が集まらなくては、レビュワーに無駄な負担をかけることになる。
レビュワーがPull Requestのレビューに時間がかかるというイメージを持ってしまうと、リードタイムが長くなる。
Pull Requestを適切なサイズに抑えることが重要。大きなPull Request1つよりも細かいPull Request 3つの方が良い。
脳内に収まらないサイズのPull Requestをレビューさせることを防ぐことができ、レビュワーの負荷が下がる。
大きなPull RequestだとBDUFになりがちだし手戻りも大きい。小さくしていけば軌道修正しやすい。 複数のPull Requestが関連する場合は、流れを明記する
レビュイーはPull Requestの流れを理解していたとしてもレビュワーはそうとも限らない。
関連するPull Requestがある場合や、この後の作業が予定されている場合はこのPull Requestがどのような位置付けに当たるのかを明記する。
チケットへの参照を含める
Pull Request提出テクニック(↑をうまく書くのがむずいなと思ったので一旦ブレスト的に出してみる)
大きさ
Pull Requestはなるべく小さく出す(もちろん意味のある単位で)
大きすぎるPull Requestは確認するのが難しく、リードタイムを伸ばすことにつながる
手戻りも大きいので出す方も大変になるし、指摘する方も「まあいいか」となりがち
タイトル
PRで何をやっているのか一目でわかるタイトルをつける
例: XXのためにYYをする / XXなのでYYをしておく
⚠️ そもそもここが表現しにくい場合はタスクの切り方が間違っている場合が多い
やっていることを伝える
具体的にやっていることの概略を書いておく
例: このPRではA, B, Cをやってます
技術的に参考にしたリンクがあれば記載しておく
Stackoverflowではなくてできるだけ一次情報が良い
公式のドキュメント
(OSS)であれば ソースコード
複数のPRと関連する場合は位置付けを書いておく
例: このPRはリファクタリング3部作の真ん中にあたり、最後にXXをすることで完成します
仕様を伝える
正とする要件がレビュワーに伝わりやすいようにする
例: 要件は【URL】にあります / デザイン: 【Figma】 or スクショ
URL先に情報がないといけない。URL先からさらに情報を探すようなことがあってはいけない
仕様やテストケースが複雑な場合は検討したプロセスを出しておく
コミュニケーションを減らす
怪しいと思っている場合や悩んでいるポイントは事前に明記しておく
Inline Comment機能があるので活用する
推し進める
レビューしてもらえない場合はレビューしてもらえるようにレビュワーに促す
必要な複雑さを持ったPull Requestもあるはず
そもそも自分のPull Requestはレビューしやすいか?を考え直してみるべし
レビューは勝ち負けじゃない
もらったコメントに必ず従わないといけないわけでもない
コードを少しでもよくできていればよい
Approveを得ていてチームのルールを守っているならマージしてしまって良い
参考